confluence-markdown-syncを使ってGitHubリポジトリ内のmdファイルをConfluenceCloudに同期させてみた
GitHubリポジトリにコミットしたドキュメントと、ConfluenceやNotion等のドキュメントスペースへコミットするドキュメントの取り扱いには頭を抱えやすいものです。
Confluence内のドキュメント取り扱いをスムーズにすべくと社内では色々と取り組みが行われているものの、個人的には「あれこれ検討しても、結局更新されないとすぐにレガシーになるものなぁ」という感想でした。Notionも検討しましたが、会社としてはConfluenceを使っている故に今度は財布の問題もでてきます。
GitHubリポジトリに突っ込んだドキュメントを妖精さんが書き写してくれないだろうかとActionsを眺めると、大体APIを頑張って触ろう、という結果になります。それでもAPIを直接触る手段以外になにかないかなと継続して調べていたところ、以下のActionを見つけました。ポイントは追記ではなく同期です。
個人で試しにConfluence Cloudのフリープランを取得して実行してみたところ、予想していたよりも手軽にやりたいことができたので記事にしてみました。
confluence-markdown-sync
GitHubリポジトリ内のmarkdownドキュメントをConfluenceに同期させます。ポイントは本当にまるっと書き換えるところです。
必要な指定は以下の通り。
| パラメータ | 詳細 |
|---|---|
| cloud | Confluence Cloudの https://xxx.atlassian.net/ の xxx 部分 |
| token | Confluence Cloudにて発行できるToken。ここから。 |
| user | ログイン時のメールアドレス |
| to | https://<cloud-id>.atlassian.net/wiki/spaces/<space>/pages/<page-id>/<title> の <page-id> 。1ドメイン内でユニークとなっており、複数スペースがあっても重複しません。 |
使い方
API Tokenを取得して、GitHubリポジトリのSecretsに追加します。
MarketPlaceのサンプルは正確ではないので、そのまま利用するとエラーになります。
- name: confluence-markdown-sync
uses: cupcakearmy/confluence-markdown-sync@v1
with:
from: 'README.md'
to: '000000'
user: '[email protected]'
cloud: 'xxxxxx'
token: ${{ secrets.CONFLUENCE_TOKEN }}
あとはActions上から実行。成功するとログに以下のようなメッセージが残ります。
Uploaded content successfully to page https://xxxxxx.atlassian.net/wiki/spaces/HOME/pages/000000/GitHub+Auto+Render
同期例
リポジトリ側で以下のように書いたとして、
# workflow-test sample id | name ----| ---- 1 | test 
GitHub上では以下のようにレンダリングされます。
Confluence上では以下の通り。
表組みは完璧ですね。画像もレンダリングされているのは、ファイルが添付されているのではなくmarkdown内のURLが有効なためです。
あとがき
やりたかったことが手軽に実現できたのは驚きでした。問題はConfluence側で再現可能なMarkdownの種類です。actions側のリポジトリには明記されていないので、試していくしかありません。
事前にページIDの決め打ちが必要であることと、同期するMarkdownで常に上書きされるため、参照専用のページとして事前に空ページを追加用意しておく必要があります。
単純なMarkdownの転写以外に、リポジトリ内で管理している設定ファイルを読み取りつつ整形してmdファイルに加筆更新し、更新したmdファイルをConfluence上に反映するというスタイルもできそうです。ドキュメントの更新にかかる負担を大幅に減らすという点で、積極的に使ってみようと思います。
